.TH std::iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::iterator \- std::iterator

.SH Synopsis
   Defined in header <iterator>
   template<

       class Category,
       class T,
       class Distance = std::ptrdiff_t,  (deprecated in C++17)
       class Pointer = T*,
       class Reference = T&

   > struct iterator;

   std::iterator is the base class provided to simplify definitions of the required
   types for iterators.

.SH Template parameters

   Category  - the category of the iterator. Must be one of iterator category tags.
   T         - the type of the values that can be obtained by dereferencing the
               iterator. This type should be void for output iterators.
   Distance  - a type that can be used to identify distance between iterators
   Pointer   - defines a pointer to the type iterated over (T)
   Reference - defines a reference to the type iterated over (T)

.SH Member types

   Member type       Definition
   iterator_category Category
   value_type        T
   difference_type   Distance
   pointer           Pointer
   reference         Reference

.SH Example

   The following example shows how to implement an input iterator by inheriting from
   std::iterator


// Run this code

 #include <algorithm>
 #include <iostream>

 template<long FROM, long TO>
 class Range
 {
 public:
     // member typedefs provided through inheriting from std::iterator
     class iterator : public std::iterator<
                                 std::input_iterator_tag, // iterator_category
                                 long,                    // value_type
                                 long,                    // difference_type
                                 const long*,             // pointer
                                 long                     // reference
                             > {
         long num = FROM;
     public:
         explicit iterator(long _num = 0) : num(_num) {}
         iterator& operator++() { num = TO >= FROM ? num + 1: num - 1; return *this; }
         iterator operator++(int) { iterator retval = *this; ++(*this); return retval; }
         bool operator==(iterator other) const { return num == other.num; }
         bool operator!=(iterator other) const { return !(*this == other); }
         reference operator*() const { return num; }
     };
     iterator begin() { return iterator(FROM); }
     iterator end() { return iterator(TO >= FROM? TO + 1 : TO - 1); }
 };

 int main()
 {
     // std::find requires an input iterator
     auto range = Range<15, 25>();
     auto itr = std::find(range.begin(), range.end(), 18);
     std::cout << *itr << '\\n'; // 18

     // Range::iterator also satisfies range-based for requirements
     for (long l : Range<3, 5>())
         std::cout << l << ' '; // 3 4 5
     std::cout << '\\n';
 }

.SH Output:

 18
 3 4 5

.SH See also

                              provides uniform interface to the properties of an
   iterator_traits            iterator
                              \fI(class template)\fP
   input_iterator_tag
   output_iterator_tag
   forward_iterator_tag       empty class types used to indicate iterator categories
   bidirectional_iterator_tag \fI(class)\fP
   random_access_iterator_tag
   contiguous_iterator_tag
   (C++20)
